Notification Webhook

Business needs to provide the endpoint URL where the notification events will be sent.

---

API Endpoint

Provided by the business

Authentication Methods Supported

Both Basic and Bearer Token methods are supported. If Basic method is chosen, business needs to set the username and password. In case of Bearer method, the corresponding token will be configured by the business.

---

1. Outbound Message Status Updates

Delivered automatically as messages transition through lifecycle states (sent, delivered, read, failed).

A. Delivered Status

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "order_update_123",
  "subscriberId": "919672242292",
  "status": "delivered",
  "deliveredAt": 1788939562
}

B. Sent Status

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "order_update_123",
  "subscriberId": "919672242292",
  "status": "sent",
  "sentAt": 1788939560
}

C. Read Status

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "order_update_123",
  "subscriberId": "919672242292",
  "status": "read",
  "readAt": 1788939570
}

D. Failed Status

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "order_update_123",
  "subscriberId": "919672242292",
  "status": "failed",
  "failedAt": 1788939565,
  "errorCode": 131026,
  "failureReason": "Message Undeliverable",
  "failureDetails": "Recipient phone number not registered on WhatsApp"
}

Properties

Field	Type	Description
messageId	string	WhatsApp channel message ID (wamid.xxx)
messageRef	string	Custom reference tag configured on the message node in Flow Builder or passed via API
subscriberId	string	Recipient customer phone number in international format without +
status	string	Current lifecycle status: sent, delivered, read, or failed
sentAt / deliveredAt / readAt / failedAt	number	Unix timestamp (epoch seconds) when the event occurred
errorCode	number	Provider failure code (present only on failure)
failureReason	string	High-level reason for failure (present only on failure)
failureDetails	string	Detailed error description from Meta (present only on failure)

---

2. Inbound Customer Messages

Delivered when a customer sends a reply or initiates a message to your WhatsApp Business number.

A. Text Message

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "919999999999",
  "type": "text",
  "receivedAt": 1788939600,
  "text": "Hello, I want to know my order status."
}

B. Image Message

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "919999999999",
  "type": "image",
  "receivedAt": 1788939600,
  "mediaUrl": "https://s3.ap-south-1.amazonaws.com/media-storage/.../receipt.jpeg",
  "caption": "Payment receipt",
  "mimeType": "image/jpeg",
  "filename": "receipt.jpeg"
}

C. Document / PDF File

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "919999999999",
  "type": "file",
  "receivedAt": 1788939600,
  "mediaUrl": "https://s3.ap-south-1.amazonaws.com/media-storage/.../invoice.pdf",
  "caption": "Invoice copy",
  "mimeType": "application/pdf",
  "filename": "invoice.pdf"
}

D. Audio / Voice Note

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "919999999999",
  "type": "audio",
  "receivedAt": 1788939600,
  "mediaUrl": "https://s3.ap-south-1.amazonaws.com/media-storage/.../audio.ogg",
  "mimeType": "audio/ogg; codecs=opus",
  "filename": "voice_note.ogg"
}

E. Video

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "919999999999",
  "type": "video",
  "receivedAt": 1788939600,
  "mediaUrl": "https://s3.ap-south-1.amazonaws.com/media-storage/.../video.mp4",
  "caption": "Product issue video",
  "mimeType": "video/mp4",
  "filename": "issue.mp4"
}

F. Location Coordinates

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "subscriberId": "919999999999",
  "wabaNumber": "919999999999",
  "type": "location",
  "receivedAt": 1788939600,
  "latitude": 12.971598,
  "longitude": 77.594566
}

Properties

Field	Type	Description
messageId	string	WhatsApp channel message ID (wamid.xxx)
subscriberId	string	Customer phone number without +
wabaNumber	string	Business WhatsApp number that received the message
type	string	Message type: text, image, file, audio, video, or location
receivedAt	number	Unix timestamp (epoch seconds) when received
text	string	Message body text (for text type)
mediaUrl	string	Direct download URL for the media attachment
caption	string	Media caption text (if attached)
mimeType	string	MIME format of the media (e.g., image/jpeg, application/pdf)
filename	string	Filename of the media attachment
latitude / longitude	number	GPS coordinates (for location type)

---

Response

• HTTP Status Code: 200 OK (successful), 4xx/5xx (error)